<!DOCTYPE html SYSTEM "about:legacy-compat">
<html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="./images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 (9.0.30) - GraalVM support</title><script type="application/javascript" data-comments-identifier="tomcat-9.0-doc/graal">
    "use strict"; // Enable strict mode

    (function() {
      var thisScript = document.currentScript;
      if (!thisScript) { // Workaround for IE <= 11
        var scripts = document.getElementsByTagName("script");
        thisScript = scripts[scripts.length - 1];
      }
      document.addEventListener("DOMContentLoaded", (function() {
        var commentsDiv = document.getElementById("comments_thread");
        var commentsShortname = "tomcat";
        var commentsIdentifier = "https://tomcat.apache.org/" +
          thisScript.getAttribute("data-comments-identifier") + ".html";

        (function(w, d) {
          if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
            var s = d.createElement("script");
            s.type = "application/javascript";
            s.async = true;
            s.src = "https://comments.apache.org/show_comments.lua?site=" +
              encodeURIComponent(commentsShortname) +
              "&page=" + encodeURIComponent(commentsIdentifier);
            d.head.appendChild(s);
          } else {
            commentsDiv.appendChild(d.createTextNode("Comments are disabled for this page at the moment."));
          }
        })(window, document);
      }), false);
    })();
  </script></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="./images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="./images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9</h1><div class="versionInfo">
          Version 9.0.30,
          <time datetime="2019-12-07">Dec 7 2019</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="index.html">Docs Home</a></li><li><a href="https://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul></div><div><h2>User Guide</h2><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="host-manager-howto.html">6) Host Manager</a></li><li><a href="realm-howto.html">7) Realms and AAA</a></li><li><a href="security-manager-howto.html">8) Security Manager</a></li><li><a href="jndi-resources-howto.html">9) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">10) JDBC DataSources</a></li><li><a href="class-loader-howto.html">11) Classloading</a></li><li><a href="jasper-howto.html">12) JSPs</a></li><li><a href="ssl-howto.html">13) SSL/TLS</a></li><li><a href="ssi-howto.html">14) SSI</a></li><li><a href="cgi-howto.html">15) CGI</a></li><li><a href="proxy-howto.html">16) Proxy Support</a></li><li><a href="mbeans-descriptors-howto.html">17) MBeans Descriptors</a></li><li><a href="default-servlet.html">18) Default Servlet</a></li><li><a href="cluster-howto.html">19) Clustering</a></li><li><a href="balancer-howto.html">20) Load Balancer</a></li><li><a href="connectors.html">21) Connectors</a></li><li><a href="monitoring.html">22) Monitoring and Management</a></li><li><a href="logging.html">23) Logging</a></li><li><a href="apr.html">24) APR/Native</a></li><li><a href="virtual-hosting-howto.html">25) Virtual Hosting</a></li><li><a href="aio.html">26) Advanced IO</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li><li><a href="rewrite.html">33) Rewrite</a></li><li><a href="cdi.html">34) CDI 2 and JAX-RS</a></li><li><a href="graal.html">35) GraalVM Support</a></li></ul></div><div><h2>Reference</h2><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet 4.0 Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.3 Javadocs</a></li><li><a href="elapi/index.html">EL 3.0 Javadocs</a></li><li><a href="websocketapi/index.html">WebSocket 1.1 Javadocs</a></li><li><a href="jaspicapi/index.html">JASPIC 1.1 Javadocs</a></li><li><a href="annotationapi/index.html">Common Annotations 1.3 Javadocs</a></li><li><a href="https://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul></div><div><h2>Apache Tomcat Development</h2><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="https://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>GraalVM support</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text">
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Setup">Setup</a></li><li><a href="#Packaging_and_Building">Packaging and Building</a></li><li><a href="#Native_image_configuration">Native image configuration</a></li><li><a href="#Building_the_native_image">Building the native image</a></li><li><a href="#Compatibility">Compatibility</a></li></ul>
</div><h3 id="Introduction">Introduction</h3><div class="text">

  <p>
    Tomcat supports using the GraalVM 19.3 Native Image tool to produce
    a native binary including the container. This documentation page
    describes the build process of such an image.
  </p>

  </div><h3 id="Setup">Setup</h3><div class="text">

  <p>
    The native image tool is much easier to use with single JARs, as a result
    the process will use the Maven shade plugin JAR packaging (fat JAR). The
    idea is to produce a single JAR that contains all necessary classes from
    Tomcat, the webapps and all additional dependencies. Although Tomcat has
    received compatibility fixes to support GraalVM native images, any library
    may not be compatible and may require replacement code (the GraalVM
    documentation has more details about this).
  </p>

  <p>
    Download and install GraalVM. The first step is then to add the
    native-image tool.
    <div class="codeBox"><pre><code>export JAVA_HOME=/absolute...path...to/graalvm-ce-javaX-x.y.z
cd $JAVA_HOME/bin
./gu install native-image</code></pre></div>
    Download the Tomcat Maven packaging from
    https://github.com/apache/tomcat/tree/master/res/tomcat-maven and place
    all the files in a folder (named tomcat-maven in this documentation.
    <div class="codeBox"><pre><code>export TOMCAT_MAVEN=/absolute...path...to/tomcat-maven</code></pre></div>
    The build process now requires both Ant and Maven.
  </p>

  </div><h3 id="Packaging_and_Building">Packaging and Building</h3><div class="text">

  <p>
    Inside the tomcat-maven folder, the directory structure is the same as for
    regular Tomcat. The main configuration files are placed in the conf folder,
    and if using the default server.xml the webapps are placed in the webapps
    folder.
  </p>

  <p>
    The first step is to build the fat Tomcat JAR with all dependencies.
    Any JSP in the webapp must all be precompiled and packaged.
    <div class="codeBox"><pre><code>cd $TOMCAT_MAVEN
mvn package
ant -Dwebapp.name=somewebapp -f graal-webapp.ant.xml</code></pre></div>
    Dependencies for the webapp should now be added to the main pom.xml,
    following with building the complete fat JAR.
    <div class="codeBox"><pre><code>mvn package</code></pre></div>
  </p>

  </div><h3 id="Native_image_configuration">Native image configuration</h3><div class="text">

  <p>
    Native images do not support any form of dynamic classloading or
    reflection unless it is defined explicitly in descriptors. Generating
    them uses a tracing agent from the GraalVM, and needs additional manual
    configuration in some cases.
  </p>

  <p>
    Run the GraalVM substrate VM using the trace agent:
    <div class="codeBox"><pre><code>$JAVA_HOME/bin/java\
        -agentlib:native-image-agent=config-output-dir=$TOMCAT_MAVEN/target/\
        -Dcatalina.base=. -Djava.util.logging.config.file=conf/logging.properties\
        -jar target/tomcat-maven-1.0.jar</code></pre></div>
  </p>

  <p>
    Now all paths from the webapp that lead to dynamic classloading
    (ex: Servlet access, websockets, etc) need to be accessed using a script
    that will exercise the webapp. Servlets may be loaded on startup
    instead of needing an actual access. Listeners may also be used to load
    additional classes on startup.
  </p>

  <p>
    The descriptors have now been generated in the agent output directory.
    At this point, further configuration must be made to add items that are
    not traced, including: base interfaces, resource bundles, BeanInfo based
    reflection, etc. Please refer to the Graal documentation for more
    information on this process.
  </p>

  </div><h3 id="Building_the_native_image">Building the native image</h3><div class="text">

  <p>
    If everything has been done properly, the native image can now be built
    using the native-image tool.
    <div class="codeBox"><pre><code>$JAVA_HOME/bin/native-image --no-server\
        --allow-incomplete-classpath --enable-https\
        --initialize-at-build-time=org.eclipse.jdt,org.apache.el.parser.SimpleNode,javax.servlet.jsp.JspFactory,org.apache.jasper.servlet.JasperInitializer,org.apache.jasper.runtime.JspFactoryImpl\
        -H:+JNI -H:+ReportUnsupportedElementsAtRuntime\
        -H:+ReportExceptionStackTraces -H:EnableURLProtocols=http,https,jar,jrt\
        -H:ConfigurationFileDirectories=$TOMCAT_MAVEN/target/\
        -H:ReflectionConfigurationFiles=$TOMCAT_MAVEN/tomcat-reflection.json\
        -H:ResourceConfigurationFiles=$TOMCAT_MAVEN/tomcat-resource.json\
        -H:JNIConfigurationFiles=$TOMCAT_MAVEN/tomcat-jni.json\
        -jar $TOMCAT_MAVEN/target/tomcat-maven-1.0.jar</code></pre></div>
    The additional <code>--static</code> parameter enables static linking of
    glibc, zlib and libstd++ in the generated binary.
  </p>

  <p>
    Running the native image is then:
    <div class="codeBox"><pre><code>./tomcat-maven-1.0 -Dcatalina.base=. -Djava.util.logging.config.file=conf/logging.properties</code></pre></div>
  </p>

  </div><h3 id="Compatibility">Compatibility</h3><div class="text">

  <p>
    Servlets, JSPs, EL, websockets, the Tomcat container, tomcat-native, HTTP/2
    are all supported out of the box in a native image.
  </p>

  <p>
    At the time of writing this documentation, JULI is not supported as the
    log manager configuration property is not supported by Graal, in addition
    to some static initializer problems, and the regular java.util.logging
    loggers and implementation should be used instead.
  </p>

  <p>
    If using the default server.xml file, some Server listeners have
    to be removed from the configuration as they are not compatible with native
    images, such as a JMX listener (JMX is unsupported) and leak prevention
    listeners (use of internal code that does not exist in Graal).
  </p>

  <p>
    Missing items for better Tomcat functionality:
    <ul>
      <li>Java serialization: Clustering and session persistence are not
        functional</li>
      <li>JMX: The usual monitoring and management is not usable</li>
      <li>java.util.logging LogManager: Configuration through a system property
        is not implemented, so standard java.util.logging must be used instead
        of JULI</li>
      <li>Static linking configuration: tomcat-native cannot be statically
        linked</li>
    </ul>
  </p>

  </div><div class="noprint"><h3 id="comments_section">
                  Comments
                </h3><div class="text"><p class="notice"><strong>Notice:</strong> This comments section collects your suggestions
                    on improving documentation for Apache Tomcat.<br><br>
                    If you have trouble and need help, read
                    <a href="https://tomcat.apache.org/findhelp.html">Find Help</a> page
                    and ask your question on the tomcat-users
                    <a href="https://tomcat.apache.org/lists.html">mailing list</a>.
                    Do not ask such questions here. This is not a Q&amp;A section.<br><br>
                    The Apache Comments System is explained <a href="./comments.html">here</a>.
                    Comments may be removed by our moderators if they are either
                    implemented or considered invalid/off-topic.
                  </p><div id="comments_thread"></div></div></div></div></div></div></div><footer><div id="footer">
    Copyright &copy; 1999-2019, The Apache Software Foundation
  </div></footer></div></body></html>